<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>PrettyProlog implementation details - the Parser Module</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<meta name="generator" content="Emacs">
<style type="text/css">
@import url("../style.css");
</style>
</head>
<body>
<div id="container">
    <div id="header">
        <h1>PrettyProlog - the Parser Module</h1>
    </div>
    <div id="content">
	<p align="left">
	    The Parser Module (package <code>prettyprolog.parser</code>) contains the Parser class and some parser exception classes. This module lies just above the Data Types Module; its only task is to read characters from a stream and produce instances of PrettyProlog data types, or throw an exception if something goes wrong. The Parser isn't really customizable; it is intended as a temporary utility until a more serious parser is developed.<br />
	The Parser's parse() method works in three stages:
	<ol>
	  <li>Stream Tokenizing - the parser reads characters from the stream until a dot is found. If the stream ends before this, an exception is thrown. Else, the parser splits the sequence of characters into tokens, and from these produces a list of Symbols, control tokens, and sub-lists (which represent Prolog lists or functors' arg lists). Again, if something goes wrong in this process, an exception is thrown.</li>
	  <li>Infix-to-prefix - the parser reorganizes the list produced in step 1, so that operators are in prefix syntax. I.e. [a, :-, b, .] becomes [:-, [a, b], .].</li>
	  <li>Term Construction - the list obtained from step 2 is used to construct terms, such as Variables, Callables, Conses etc. If the parser is unable to construct a Term with the given data, it throws an exception. Else, it returns the Term.</li>
	</ol>
	The programmer can specify a different terminator token instead of the dot; the first phase reads until a dot anyway, but the third phase won't throw an exception if after the parsed Term the programmer-specified token is found instead of the dot.<br />
	<h4 align="left">More details on Phase 1</h4>
	Let's examine in detail Phase 1 of the above list (other phases are quite trivial to understand). The Parser reads character-by-character, and decides what to do basing on the last character read. Let ch be this character, and ls the (initially empty) list of tokens that will be the output of Phase 1:
	<ul>
	  <li>If ch = '.' the DOT special token is added to ls, and ls is returned (Phase 1 terminates).</li>
	  <li>If ch = ',' the COMMA special token is added to ls.</li>
	  <li>If ch = '(' the tokenize() method (the one which implements Phase 1) is recurively called and the result of the call is added to ls.</li>
	  <li>If ch = ')' ls is returned.</li>
	  <li>If ch = '[' the OPEN_BRACKET special token is added to ls, then the tokenize() method is recursively called and the return value is added to ls.</li>
	  <li>If ch = ']': if a '[' was previously found, the CLOSE_BRACKET special token is added to ls. Else, ch is marked as unread (so that the parser will process it again) and ls is returned. This is needed for recursion to work properly.</li>
	  <li>If ch = '|' the PIPE special token is added to ls.</li>
	  <li>If ch = '"' a CharString is parsed by the parseString() method, and it is added to ls.</li>
	  <li>If ch is a digit, a Real is parsed by the parseNumber() method, and it is added to ls.</li>
	  <li>In every other case, the parseSymbol() method is called and the result is added to ls.</li>
	</ul>
	So, the list ls is made of Symbols (constants, variables, or names of Callables), special tokens like DOT, COMMA etc., and sub-lists which represent Callable arg lists when they follow a Symbol, or Prolog lists when they are enclosed between the OPEN_BRACKET and CLOSE_BRACKET special tokens.
	<br /><br />
	<b>Exceptions.</b> If any private method called by parse() throws an exception, it is not caught and it is the responsibility of the callee of the parse() method to catch it.<br /><br />
	For further info, see the javadocs.
	</p>
    </div>
    <div id="footer"><a href="../index.html">General info</a> | <a href="../javadoc/index.html">Javadocs</a> | <a href="index.html">Implementation details</a></div>
</div>
</body>
</html>